{
    title:  'Scripts and Stylesheets',
    crumbs: [ 
        { "User's Guide": "index.html" },
    ],
}
   
        <h1>Scripts and Stylesheets</h1>
        <p>Managing scripts and stylesheets in a web application involves several common tasks:</p>
        <ul>
            <li>Selecting raw or minified versions</li>
            <li>Including excluding map files</li>
            <li>Minifying files</li>
        </ul>
        <p>These tasks vary depending on whether the web site is being developed, tested or
        prepared for production. Expansive supports these use cases via the
        <em><a href="https://github.com/embedthis/exp-css">exp-css</a></em> and the
        <em><a href="https://github.com/embedthis/exp-js">exp-js</a></em>.</p>

        <h2>exp-css</h2>
        <p>The <em>exp-css</em> plugin manages CSS files and provides the Expansive transformations:</p>
        <ul>
            <li>prefix &mdash; Add browser vendor prefixes to CSS rules</li>
            <li>render &mdash; Generate HTML link elements for required CSS files</li>
            <li>minify &mdash; Minify CSS files to compress</li>
            <li>extract &mdash; Extract inline styles to support CSP</li>
        </ul>
        <p>The <em>prefix</em> service automatically adds vendor prefixes, such as <em>webkit-</em> to 
        CSS rules. In this way, you can use only the standard, portable CSS rules and prefixes will be 
        prepended as required. The prefix plugin uses the <em>autoprefixer</em> tool.</p>

        <p>The <em>render</em> service will intelligently select raw, minified and map files as required. 
        The default configuration is set for a debug mode where minified files will be used if a corresponding
        map file exists, otherwise the raw CSS file is used. A release mode can be selected via configuration
        properties a minified version can be selected.</p>

        <p>The <em>minify</em> service will minify CSS files to reduce their size.</p>

        <h2>Configuration Properties</h2>
        <p>The exp-css services can be enabled and configured via properties in the 
        <em>expansive.json</em> configuration file.</p>

        <table class="ui celled table" title="exp-css">
            <thead>
                <tr><th>Property</th><th>Description</th></tr>
            </thead>
            <tbody>
                <tr><td>dotmin</td><td>Use <em>.min.css</em> as the output file extension 
                    after minification. Otherwise will be <em>.css</em>. Default to true.</td></tr>
                <tr><td>enable</td><td>Enable the service.</td></tr>
                <tr><td>files</td><td>Array of file patterns to process. Defaults to 
                    <em>['**.css', '!**.css.map', '!*.less']</em>. May include negated patterns beginning with <em>!</em>.</td></tr>
                <tr><td>minify</td><td>Enable minifying of Javascript files. 
                    Default to false.</td></tr>
                <tr><td>prefix</td><td>Autoprefix styles using vendor specific browser prefixes. Defaults to true.</td></tr>
                <tr><td>usemap</td><td>Use minified stylesheet if corresponding source maps 
                    is present. Defaults to true.</td></tr>
                <tr><td>usemin</td><td>Use minified stylesheet if present. Defaults to null. 
                    Set explicitly to false to disable the use of minified resources.</td></tr>
            </tbody>
        </table>

        <p>The default configuration without any configuration properties suits a development profile where 
        minified CSS files are used only if they have an associated map file. A default release configuration 
        in <em>expansive.json</em> would look like:</p>

        <pre class="code">{
    "release": {
        "services": {
            "css": {
                "minify": true
            }
        }
    }
}
</pre>
        <p>This would then be selected via <em>pak mode release</em>.</p>

        <h2>exp-js</h2>
        <p>The <em>exp-js</em> plugin managed JS script files and provides the Expansive services:</p>
        <ul>
            <li>minify&mdash; Minify JS files to compress</li>
            <li>render&mdash; Generate HTML link elements for required JS files</li>
            <li>extract &mdash; Extract inline scripts to support CSP</li>
        </ul>

        <h2>Configuration Properties</h2>
        <p>The exp-js services can be enabled and configured via properties in the 
            <em>expansive.json</em> configuration file.</p>

        <table class="ui celled table" title="exp-js">
            <thead>
                <tr><th>Property</th><th>Description</th></tr>
            </thead>
            <tbody>
                <tr><td>dotmin</td><td>Use <em>.min.js</em> as the output file extension 
                    after minification. Otherwise will be <em>.js</em>. Default to true.</td></tr>
                <tr><td>enable</td><td>Enable the service.</td></tr>
                <tr><td>files</td><td>Array of file patterns to process. Defaults to 
                    <em>['lib/**.js', '!lib/**.min.map']</em>.
                    May include negated patterns beginning with <em>!</em>.</td></tr>
                <tr><td>force</td><td>Always minify even if a minified version exists in contents. Default to false</td></tr>
                <tr><td>minify</td><td>Enable minifying of Javascript files. 
                    Default to false.</td></tr>
                <tr><td>usemap</td><td>Use minified stylesheet if corresponding source maps 
                    is present. Defaults to true.</td></tr>
                <tr><td>usemin</td><td>Use minified stylesheet if present. Defaults to null. 
                    Set explicitly to false to disable the use of minified resources.</td></tr>
            </tbody>
        </table>

        <p>The default configuration without any configuration properties, suits a development profile where 
        minified JS files are used only if they have an associated map file. A default release configuration 
        in <em>expansive.json</em> would look like:</p>

        <pre class="code">{
    "release": {
        "services": {
            "js": {
                "minify": true,
                "usemap": false
            }
        }
    }
}
</pre>

        <h2>Automated Library Configuration</h2>

        <p>You can manually define your &lt;script&gt; and stylesheet &lt;link&gt; elements if you wish.
        However, as you develop your application and install various script and stylesheet libraries, you will 
        need to manually add or modify references to these script and stylesheet references. 
        If there are dependencies between libraries, order matters. For example, 
        <a href="http://getbootstrap.com">Bootstrap</a>
        must be loaded after <a href="http://jquery.com/">jQuery</a>. While this is not too tedious, 
        Expansive provides an elegant way to automate the generation and maintenance of script and stylesheet
        element references. As you install and remove packages, the script and stylesheet elements can be 
        adjusted automatically.</p>

        <p>If you install your script and CSS libraries using the <a href="http://embedthis.com/pak">Pak</a>
        package manager, Expansive can automatically determine the required script and CSS references and can
        correctly generate them for you in your HTML.</p>

        <p>The <em>exp-css</em> plugin provides the <em>renderStyles</em> API and the <em>exp-js</em> service
        offer the <em>renderScripts</em> API. These APIs can be placed in your HTML where you would like
        to generate your script and CSS references. For example, consider an application that installs the following 
        libraries: </p>
        <ul>
            <li><a href="http://getbootstrap.com">Bootstrap</a></li>
            <li><a href="http://getbootstrap.com">Angular</a></li>
            <li><a href="http://getbootstrap.com">Angular-Route</a></li>
            <li><a href="http://getbootstrap.com">Angular-Animate</a></li>
            <li><a href="http://getbootstrap.com">Font-Awesome</a></li>
        </ul>
        <pre>$ pak install angular angular-route angular-animate bootstrap font-awesome exp-js exp-css
   [Install] angular 1.3.14
   [Install] angular-route 1.3.9
   [Install] angular-animate 1.3.9
   [Install] jquery 2.1.3
   [Install] bootstrap 3.3.2
   [Install] font-awesome 4.3.0
   [Install] exp-js 0.2.0
   [Install] exp-css 0.2.0
   [Install] jquery 2.1.3
   [Install] bootstrap 3.3.2</pre>

        <p>The following layout page can use the <em>renderStyles</em> and <em>renderScripts</em>
        to automatically generate the required HTML for the stylesheets and scripts.</p>


        <pre class="code">&lt;html&gt;
&lt;head&gt;
    <b>&lt;@ renderStyles() @&gt;
    &lt;@ renderScripts() @&gt;</b>
&lt;/head&gt;
&lt;body&gt;
    &lt;@ content @&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>

        <p>This will be rendered as:</p>
        <pre class="code">&lt;html&gt;
&lt;head&gt;
    <b>&lt;link href="angular/angular-csp.css" ... /&gt;
    &lt;link href="bootstrap/css/bootstrap.min.css" ... /&gt;
    &lt;link href="bootstrap/css/bootstrap-theme.min.css" ... /&gt;
    &lt;link href="font-awesome/css/font-awesome.min.css" ... /&gt;

    &lt;script src="angular/angular.min.js"&gt;&lt;/script&gt;
    &lt;script src="angular-animate/angular-animate.min.js"&gt;&lt;/script&gt;
    &lt;script src="angular-route/angular-route.min.js"&gt;&lt;&lt;/script&gt;
    &lt;script src="jquery/jquery.min.js"&gt;&lt;/script&gt;
    &lt;script src="bootstrap/js/bootstrap.js"&gt;&lt;/script&gt;</b>
&lt;/head&gt;
&lt;/html&gt;
</pre>
    <p>Note that all required stylesheets and scripts are rendered in the correct order.</p>

    <h3>renderScripts and renderStyles</h3>
    <p>The <em>renderScripts</em> and <em>renderStyles</em> APIs have the following signatures:</p>
    <pre class="code">function renderScripts(filter = null, extras = [])
function renderStyles(filter = null, extras = [])</pre>
    <p>Where <em>filter</em> is an optional filename pattern or array of patterns. If not supplied, then all the
        default the scripts/styles are rendered. If <em>filter</em> is provided, only the files that match the 
        <em>filter</em> will be rendered. Wild-cards are supported including
        <em>**</em> to match in any directory and <em>!</em> to negate a pattern and exclude a filename.
        The optional <em>extras</em> argument is an array of extra files to render. Combined, these two arguments
        provide the ability to select, include or exclude files.</p>

    <p>You can also add files to be rendered by modifying the <em>collections.scripts</em> and
    <em>collections.styles</em> lists.</p>

    <h3>Prerequisites</h3>
    <p>To use this automatic configuration, you must meet these prerequisites</p>
    <ul>
        <li>You must install the relevant libraries using the <a href="http://embedthis.com/pak/">Pak</a> 
            package manager.</li>
        <li>You must have the 
            <em><a href="https://github.com/embedthis/exp-css">exp-css</a></em> and
            the <em><a href="https://github.com/embedthis/exp-js">exp-js</a></em> plugins installed.</li>
        <li>You must add <em>renderStyles()</em> and <em>renderScripts()</em> to your page or layout.</li>
    </ul>

    <h2>Want More?</h2>
    <p>Use the <em><a href="https://github.com/embedthis/exp-less">exp-less</a></em> to process Less stylesheets
    and the  <em><a href="https://github.com/embedthis/exp-sass">exp-sass</a></em> to process Sass stylesheets.</p> 
